Skip to content

docs(starter): clarify preview approval and branch selection - #333

Open
arniebradfo wants to merge 1 commit into
build/hub/newfrom
docs/prototype-preview-and-branches
Open

arniebradfo wants to merge 1 commit into
build/hub/newfrom
docs/prototype-preview-and-branches

Conversation

@arniebradfo

Copy link
Copy Markdown
Collaborator

Why

A prototype edit could stall twice. The agent asked for another approval to start a local preview, then discovered at publication that its branch name could not trigger the repository's build workflow.

What changes

A request to create or change a prototype now covers starting the repository's declared local preview. The agent reuses a running preview when available and uses the actual URL it prints. Host permissions, dependency and plugin installation, committing, pushing, publishing, and Hub changes keep their separate approval rules.

The starter checks the repository's publishing workflow before choosing a prototype branch. A repository that accepts proto/** can use a name like proto/about-sans-serif, which is also eligible for automatic Hub registration. The agent checks the branch, commit and workflow again before publication. Workflow access and a matching trigger are separate checks.

This updates the copied instructions, skills, context templates and contributor guides. It changes no workflow, app code or repository configuration. A fresh Copilot app session is still needed to verify that the agent follows the updated guidance.

Storybook screenshots

Not applicable: no story presentation changed.

Treat the declared local preview as part of prototype work. Check publishing branch filters before choosing a branch, and recheck them before committing and pushing without changing publication permissions.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@arniebradfo
arniebradfo requested review from a team and nshki as code owners November 21, 2026 00:40
Copilot AI adaptive review requested due to automatic review settings November 21, 2026 00:40
Comment thread starter/AGENTS.md

A request to create or modify a prototype authorizes starting the repository's declared loopback dev or preview command for implementation and rendered validation. No separate approval is needed unless the user or repository policy explicitly requires it. Follow the [canvas preflight](README.md#canvas-preflight) where it applies and respect host permission prompts. Read-only research and standalone reviews do not grant this permission.

Reuse a responsive preview for this worktree. Otherwise, run the documented command, use the actual URL it prints, and verify that the requested route renders. Do not guess a port or start a duplicate server.
Comment thread starter/AGENTS.md

### Implicit user authorization for routine local prototype execution

A request to create or modify a prototype authorizes starting the repository's declared loopback dev or preview command for implementation and rendered validation. No separate approval is needed unless the user or repository policy explicitly requires it. Follow the [canvas preflight](README.md#canvas-preflight) where it applies and respect host permission prompts. Read-only research and standalone reviews do not grant this permission.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The contributor guidance can direct agents to inspect the wrong publishing workflow when .github/replica.json selects a custom path, leaving branch selection capable of producing no Build.

1 open issue
What changed in this PR

This documentation-only pull request clarifies local-preview authorization and workflow-aware prototype branch selection across the starter guidance and related Hub documentation.

Changes:

  • Allows declared local preview startup without repeated approval while preserving separate approvals for installation, commits, pushes, publishing, and Hub changes.
  • Adds workflow and branch checks before prototype creation and publication.
  • Synchronizes starter skills, context templates, repository setup guidance, and Hub Actions documentation.
File Description
starter/​README.md Updates starter onboarding with local-preview authorization and workflow-aware prototype publishing guidance.
starter/​AGENTS.md Defines preview authorization, workflow-based branch selection, and publication checks.
starter/​.agents/​skills/​prototype-controls/​SKILL.md Aligns Controls authoring with the local-preview authorization policy.
starter/​.agents/​skills/​prototype-controls/​references/​authoring.md Updates Controls authoring and validation guidance for local previews.
starter/​.agents/​skills/​create-prototype/​SKILL.md Adds workflow-aware branch selection before creating or renaming prototype branches.
starter/​.agents/​skills/​browser-canvas-validation/​WORKFLOW.md Allows authorized local preview startup during browser and canvas validation.
starter/​.agents/​context-templates/​REPOSITORY.md Documents publishing workflow, branch patterns, and repository branch-control requirements.
starter/​.agents/​context-templates/​BROWSER-VALIDATION.md Documents preview authorization, readiness checks, and actual preview URL discovery.
hub/​docs/​github-actions-builds.md Explains workflow branch filters and automatic registration of eligible prototype branches.
docs/​prototype-repository-setup.md Connects later prototype work to the updated preview and branch-selection policies.

Review effort: Lite (adaptive)

Comment thread starter/AGENTS.md

## Choose a prototype branch

Before creating or renaming a prototype branch, inspect `.github/workflows/replica.yml` or the workflow named in the repository's publishing guide. Check the `push` branch patterns, including exclusions. Choose a descriptive non-default name that satisfies both the workspace naming rules and the workflow, such as `proto/about-sans-serif` when `proto/**` matches. Use `proto/` for automatic registration in Hub, but do not assume the workflow accepts that prefix.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants